home *** CD-ROM | disk | FTP | other *** search
/ LAUNCH 17 / LAUNCH.BIN / mac / Install These / NetSprocket 1.1 GM / NetSprocket.h < prev    next >
Text File  |  1997-09-18  |  14KB  |  581 lines
  1. /*
  2.  *    File:            NetSprocket.h
  3.  *
  4.  *    Version:        Apple Game Sprockets, NetSprocket 1.0.2
  5.  *
  6.  *    Dependencies:    Universal Interfaces 2.1.2 on ETO #20
  7.  *                    Open Transport interfaces 1.1
  8.  *
  9.  *    Contents:        Public interfaces for NetSprocket.
  10.  *
  11.  *    Bugs:            If you find a problem with this file or NetSprocketLib,
  12.  *                    please send e-mail describing the problem in enough detail
  13.  *                    to be reproduced, and include the version number above, the
  14.  *                    version of MacOS and hardware configuration information to
  15.  *                    sprockets@adr.apple.com.
  16.  *
  17.  *    Copyright (c) 1996 Apple Computer, Inc.  All rights reserved.
  18.  */
  19.  
  20. #ifndef __NETSPROCKET__
  21. #define __NETSPROCKET__
  22.  
  23. #ifndef __TYPES__
  24. #include <Types.h>
  25. #endif
  26.  
  27. #ifndef __EVENTS__
  28. #include <Events.h>
  29. #endif
  30.  
  31. #ifndef __OPENTRANSPORT__
  32. #include <OpenTransport.h>
  33. #endif
  34.  
  35. #ifndef __OPENTPTINTERNET__
  36. #include <OpenTptInternet.h>
  37. #endif
  38.  
  39. #if PRAGMA_ALIGN_SUPPORTED
  40. #pragma options align=power
  41. #endif
  42.  
  43. #if PRAGMA_IMPORT_SUPPORTED
  44. #pragma import on
  45. #endif
  46.  
  47. #define kNSpMaxPlayerNameLen        31
  48. #define kNSpMaxGroupNameLen            31
  49. #define kNSpMaxPasswordLen            31
  50. #define kNSpMaxGameNameLen            31
  51. #define kNSpMaxDefinitionStringLen    255
  52.  
  53.  
  54. /* NetSprocket basic types */
  55. typedef    struct NSpGamePrivate        *NSpGameReference;
  56. typedef    struct NSpProtocolPrivate    *NSpProtocolReference;
  57. typedef    struct NSpListPrivate        *NSpProtocolListReference;
  58. typedef struct NSPAddressPrivate    *NSpAddressReference;
  59. typedef SInt32                        NSpEventCode;
  60. typedef    SInt32                        NSpGameID;
  61. typedef    SInt32                        NSpPlayerID;
  62. typedef NSpPlayerID                    NSpGroupID;
  63. typedef UInt32                        NSpPlayerType;
  64. typedef SInt32                        NSpFlags;
  65. typedef Str31                        NSpPlayerName;
  66.  
  67. /* Individual player info */
  68. typedef struct NSpPlayerInfo
  69. {
  70.     NSpPlayerID        id;
  71.     NSpPlayerType    type;
  72.     NSpPlayerName    name;
  73.     UInt32            groupCount;
  74.     NSpGroupID        groups[kVariableLengthArray];
  75. } NSpPlayerInfo, *NSpPlayerInfoPtr;
  76.  
  77.     
  78. /* list of all players */
  79. typedef struct NSpPlayerEnumeration
  80. {
  81.     UInt32                count;
  82.     NSpPlayerInfoPtr    playerInfo[kVariableLengthArray];
  83. } NSpPlayerEnumeration, *NSpPlayerEnumerationPtr;
  84.  
  85.  
  86. /* Individual group info */
  87. typedef struct NSpGroupInfo
  88. {
  89.     NSpGroupID    id;
  90.     UInt32        playerCount;
  91.     NSpPlayerID    players[kVariableLengthArray];
  92. } NSpGroupInfo, *NSpGroupInfoPtr;
  93.  
  94.  
  95. /* List of all groups */
  96. typedef struct NSpGroupEnumeration
  97. {
  98.     UInt32            count;
  99.     NSpGroupInfoPtr    groups[kVariableLengthArray];
  100. } NSpGroupEnumeration, *NSpGroupEnumerationPtr;
  101.  
  102. /* Topology types */
  103. typedef UInt32 NSpTopology;
  104. enum
  105. {
  106.     kNSpClientServer =     0x00000001
  107. };
  108.  
  109. /* Game information */
  110. typedef struct NSpGameInfo
  111. {
  112.     UInt32        maxPlayers;
  113.     UInt32        currentPlayers;
  114.     UInt32        currentGroups;
  115.     NSpTopology    topology;
  116.     UInt32        reserved;
  117.     Str31        name;
  118.     Str31        password;
  119. } NSpGameInfo;
  120.     
  121.     
  122. /* Structure used for sending and receiving network messages */
  123. typedef struct NSpMessageHeader
  124. {
  125.     UInt32        version;    /* Used by NetSprocket.  Don't touch this */
  126.     SInt32        what;        /* The kind of message (e.g. player joined) */
  127.     NSpPlayerID    from;        /* ID of the sender */
  128.     NSpPlayerID    to;            /* (player or group) id of the intended recipient */
  129.     UInt32        id;            /* Unique ID for this message & (from) player */
  130.     UInt32        when;        /* Timestamp for the message */
  131.     UInt32        messageLen;    /* Bytes of data in the entire message (including the header) */
  132. } NSpMessageHeader;
  133.  
  134.  
  135. /* NetSprocket-defined message structures */
  136.  
  137. typedef struct NSpErrorMessage
  138. {
  139.     NSpMessageHeader    header;
  140.     OSStatus            error;
  141. } NSpErrorMessage;
  142.  
  143.  
  144. typedef struct NSpJoinRequestMessage
  145. {
  146.     NSpMessageHeader    header;
  147.     NSpPlayerName        name;
  148.     Str31                password;
  149.     UInt32                type;
  150.     UInt32                customDataLen;
  151.     UInt8                customData[kVariableLengthArray];
  152. } NSpJoinRequestMessage;
  153.  
  154.  
  155. typedef struct NSpJoinApprovedMessage
  156. {
  157.     NSpMessageHeader    header;
  158. } NSpJoinApprovedMessage;
  159.  
  160.  
  161. typedef struct NSpJoinDeniedMessage
  162. {
  163.     NSpMessageHeader    header;
  164.     Str255                reason;
  165. } NSpJoinDeniedMessage;
  166.  
  167.  
  168. typedef struct NSpPlayerJoinedMessage
  169. {
  170.     NSpMessageHeader    header;
  171.     UInt32                playerCount;
  172.     NSpPlayerInfo            playerInfo;    
  173. } NSpPlayerJoinedMessage;
  174.  
  175.  
  176. typedef struct NSpPlayerLeftMessage
  177. {
  178.     NSpMessageHeader    header;
  179.     UInt32                playerCount;
  180.     NSpPlayerID            playerID;
  181.     NSpPlayerName        playerName;
  182. } NSpPlayerLeftMessage;
  183.  
  184. typedef struct NSpHostChangedMessage
  185. {
  186.     NSpMessageHeader    header;
  187.     NSpPlayerID            newHost;
  188. } NSpHostChangedMessage;
  189.  
  190.  
  191. typedef struct NSpGameTerminatedMessage
  192. {
  193.     NSpMessageHeader    header;
  194. } NSpGameTerminatedMessage;
  195.  
  196.  
  197. /* Different kinds of messages.  These can NOT be bitwise ORed together */
  198. enum
  199. {
  200.     kNSpSendFlag_Junk =         0x00100000,        /* will be sent (try once) when there is nothing else pending */
  201.     kNSpSendFlag_Normal =         0x00200000,        /* will be sent immediately (try once) */
  202.     kNSpSendFlag_Registered =     0x00400000        /* will be sent immediately (guaranteed, in order) */
  203. };
  204.  
  205.  
  206. /* Options for message delivery.  These can be bitwise ORed together with each other,
  207.         as well as with ONE of the above */
  208. enum 
  209. {
  210.     kNSpSendFlag_FailIfPipeFull =     0x00000001,
  211.     kNSpSendFlag_SelfSend =         0x00000002,
  212.     kNSpSendFlag_Blocking =         0x00000004
  213. };
  214.  
  215.  
  216. /* Options for Hosting Joining, and Deleting games */
  217. enum
  218. {
  219.     kNSpGameFlag_DontAdvertise            =    0x00000001,
  220.     kNSpGameFlag_ForceTerminateGame     =     0x00000002
  221. };
  222.  
  223. /* Message "what" types */
  224. /* Apple reserves all negative "what" values (anything with bit 32 set) */ 
  225. enum 
  226. {
  227.     kNSpSystemMessagePrefix = 0x80000000,
  228.     kNSpError =                 kNSpSystemMessagePrefix | 0x7FFFFFFF,
  229.     kNSpJoinRequest =         kNSpSystemMessagePrefix | 0x00000001,
  230.     kNSpJoinApproved =         kNSpSystemMessagePrefix | 0x00000002,
  231.     kNSpJoinDenied =         kNSpSystemMessagePrefix | 0x00000003,
  232.     kNSpPlayerJoined =         kNSpSystemMessagePrefix | 0x00000004,
  233.     kNSpPlayerLeft =         kNSpSystemMessagePrefix | 0x00000005,
  234.     kNSpHostChanged =         kNSpSystemMessagePrefix | 0x00000006,
  235.     kNSpGameTerminated=     kNSpSystemMessagePrefix | 0x00000007
  236. };
  237.  
  238.  
  239. /* Special TPlayerIDs  for sending messages */
  240. enum
  241. {
  242.     kNSpAllPlayers =     0x00000000,
  243.     kNSpHostOnly =        0xFFFFFFFF
  244. };
  245.     
  246. #ifdef __cplusplus
  247. extern "C" {
  248. #endif
  249.  
  250. /************************  Initialization  ************************/
  251.  
  252. OSStatus NSpInitialize(
  253.     UInt32                         inStandardMessageSize, 
  254.     UInt32                         inBufferSize, 
  255.     UInt32                         inQElements, 
  256.     NSpGameID                     inGameID, 
  257.     UInt32                         inTimeout);
  258.  
  259.  
  260. /**************************  Protocols  **************************/
  261.  
  262. /* Programmatic protocol routines */
  263. OSStatus NSpProtocol_New(
  264.     const char*                 inDefinitionString, 
  265.     NSpProtocolReference*        outReference);
  266.  
  267. void NSpProtocol_Dispose(
  268.     NSpProtocolReference         inProtocolRef);
  269.  
  270. OSStatus NSpProtocol_ExtractDefinitionString(
  271.     NSpProtocolReference         inProtocolRef, 
  272.     char*                        outDefinitionString);
  273.  
  274.  
  275. /* Protocol list routines */
  276. OSStatus NSpProtocolList_New(
  277.     NSpProtocolReference         inProtocolRef,
  278.     NSpProtocolListReference*    outList);
  279.  
  280. void NSpProtocolList_Dispose(
  281.     NSpProtocolListReference     inProtocolList);
  282.  
  283. OSStatus NSpProtocolList_Append(
  284.     NSpProtocolListReference     inProtocolList,
  285.     NSpProtocolReference         inProtocolRef);
  286.  
  287. OSStatus NSpProtocolList_Remove(
  288.     NSpProtocolListReference     inProtocolList, 
  289.     NSpProtocolReference         inProtocolRef);
  290.  
  291. OSStatus NSpProtocolList_RemoveIndexed(
  292.     NSpProtocolListReference     inProtocolList,
  293.     UInt32                         inIndex);
  294.  
  295. UInt32 NSpProtocolList_GetCount(
  296.     NSpProtocolListReference     inProtocolList);
  297.  
  298. NSpProtocolReference NSpProtocolList_GetIndexedRef(
  299.     NSpProtocolListReference     inProtocolList,
  300.     UInt32                         inIndex);
  301.  
  302.  
  303. /* Helpers */
  304. NSpProtocolReference NSpProtocol_CreateAppleTalk(
  305.     ConstStr31Param             inNBPName,
  306.     ConstStr31Param             inNBPType, 
  307.     UInt32                         inMaxRTT,
  308.     UInt32                         inMinThruput);
  309.  
  310. NSpProtocolReference NSpProtocol_CreateIP(
  311.     InetPort                     inPort,
  312.     UInt32                         inMaxRTT,
  313.     UInt32                         inMinThruput);
  314.  
  315.  
  316. /***********************  Human Interface  ************************/
  317. typedef pascal Boolean (*NSpEventProcPtr) (EventRecord* inEvent);
  318.  
  319.  
  320. NSpAddressReference NSpDoModalJoinDialog(
  321.     ConstStr31Param             inGameType, 
  322.     ConstStr255Param             inEntityListLabel,
  323.     NSpPlayerName                ioName, 
  324.     Str31                         ioPassword, 
  325.     NSpEventProcPtr             inEventProcPtr);
  326.  
  327. Boolean NSpDoModalHostDialog(
  328.     NSpProtocolListReference     ioProtocolList, 
  329.     Str31                         ioGameName, 
  330.     NSpPlayerName                ioPlayerName,
  331.     Str31                         ioPassword, 
  332.     NSpEventProcPtr             inEventProcPtr);
  333.  
  334.  
  335. /*********************  Hosting and Joining  **********************/
  336.  
  337. OSStatus NSpGame_Host(
  338.     NSpGameReference*            outGame, 
  339.     NSpProtocolListReference     inProtocolList, 
  340.     UInt32                         inMaxPlayers, 
  341.     ConstStr31Param             inGameName, 
  342.     ConstStr31Param             inPassword,
  343.     ConstStr31Param             inPlayerName, 
  344.     NSpPlayerType                 inPlayerType, 
  345.     NSpTopology                 inTopology,
  346.     NSpFlags                     inFlags);
  347.  
  348. OSStatus NSpGame_Join(
  349.     NSpGameReference*            outGame, 
  350.     NSpAddressReference         inAddress, 
  351.     ConstStr31Param             inName,
  352.     ConstStr31Param             inPassword,
  353.     NSpPlayerType                 inType, 
  354.     void*                        inCustomData,
  355.     UInt32                         inCustomDataLen,  
  356.     NSpFlags                     inFlags);
  357.  
  358. OSStatus NSpGame_EnableAdvertising(
  359.     NSpGameReference             inGame, 
  360.     NSpProtocolReference         inProtocol, 
  361.     Boolean                     inEnable);
  362.  
  363. OSStatus NSpGame_Dispose(
  364.     NSpGameReference             inGame, 
  365.     NSpFlags                     inFlags);
  366.  
  367. OSStatus NSpGame_GetInfo(
  368.     NSpGameReference             inGame,
  369.     NSpGameInfo                  *ioInfo);
  370.  
  371. /**************************  Messaging  **************************/
  372.  
  373. OSStatus NSpMessage_Send(
  374.     NSpGameReference             inGame, 
  375.     NSpMessageHeader*            inMessage, 
  376.     NSpFlags                     inFlags);
  377.  
  378. NSpMessageHeader *NSpMessage_Get(
  379.     NSpGameReference             inGame);
  380.  
  381. void NSpMessage_Release(
  382.     NSpGameReference             inGame, 
  383.     NSpMessageHeader*            inMessage);
  384.  
  385. /* Helpers */
  386. OSStatus NSpMessage_SendTo(
  387.     NSpGameReference             inGame,
  388.     NSpPlayerID                    inTo,
  389.     SInt32                        inWhat, 
  390.     void*                        inData,
  391.     UInt32                        inDataLen, 
  392.     NSpFlags                     inFlags);
  393.     
  394.  
  395. /*********************  Player Information  **********************/
  396.  
  397. NSpPlayerID NSpPlayer_GetMyID(
  398.     NSpGameReference             inGame);
  399.  
  400. OSStatus NSpPlayer_GetInfo(
  401.     NSpGameReference             inGame, 
  402.     NSpPlayerID                 inPlayerID, 
  403.     NSpPlayerInfoPtr*            outInfo);
  404.  
  405. void NSpPlayer_ReleaseInfo(
  406.     NSpGameReference             inGame, 
  407.     NSpPlayerInfoPtr             inInfo);
  408.  
  409. OSStatus NSpPlayer_GetEnumeration(
  410.     NSpGameReference             inGame, 
  411.     NSpPlayerEnumerationPtr*    outPlayers);
  412.  
  413. void NSpPlayer_ReleaseEnumeration(
  414.     NSpGameReference             inGame, 
  415.     NSpPlayerEnumerationPtr     inPlayers);
  416.  
  417. UInt32 NSpPlayer_GetRoundTripTime(
  418.     NSpGameReference             inGame, 
  419.     NSpPlayerID                 inPlayer); 
  420.  
  421. UInt32 NSpPlayer_GetThruput(
  422.     NSpGameReference             inGame, 
  423.     NSpPlayerID                 inPlayer); 
  424.  
  425.  
  426. /*********************  Group Management  **********************/
  427.  
  428. OSStatus NSpGroup_New(
  429.     NSpGameReference             inGame, 
  430.     NSpGroupID*                    outGroupID);
  431.  
  432. OSStatus NSpGroup_Dispose(
  433.     NSpGameReference             inGame, 
  434.     NSpGroupID                     inGroupID);
  435.  
  436. OSStatus NSpGroup_AddPlayer(
  437.     NSpGameReference             inGame, 
  438.     NSpGroupID                     inGroupID, 
  439.     NSpPlayerID                 inPlayerID);
  440.  
  441. OSStatus NSpGroup_RemovePlayer(
  442.     NSpGameReference             inGame, 
  443.     NSpGroupID                     inGroupID,
  444.     NSpPlayerID                 inPlayerID);
  445.  
  446. OSStatus NSpGroup_GetInfo(
  447.     NSpGameReference             inGame, 
  448.     NSpGroupID                     inGroupID, 
  449.     NSpGroupInfoPtr*            outInfo);
  450.  
  451. void NSpGroup_ReleaseInfo(
  452.     NSpGameReference             inGame, 
  453.     NSpGroupInfoPtr             inInfo);
  454.  
  455. OSStatus NSpGroup_GetEnumeration(
  456.     NSpGameReference             inGame, 
  457.     NSpGroupEnumerationPtr*        outGroups);
  458.  
  459. void NSpGroup_ReleaseEnumeration(
  460.     NSpGameReference             inGame, 
  461.     NSpGroupEnumerationPtr         inGroups);
  462.  
  463.  
  464. /**************************  Utilities  ***************************/
  465.  
  466. NumVersion NSpGetVersion(void);
  467.  
  468. void NSpClearMessageHeader(
  469.     NSpMessageHeader*            inMessage);
  470.  
  471. UInt32 NSpGetCurrentTimeStamp(
  472.     NSpGameReference             inGame);
  473.  
  474. NSpAddressReference    NSpConvertOTAddrToAddressReference(
  475.     OTAddress*                    inAddress);
  476.  
  477. OTAddress *NSpConvertAddressReferenceToOTAddr(
  478.     NSpAddressReference         inAddress);
  479.  
  480. void NSpReleaseAddressReference(
  481.     NSpAddressReference         inAddress);
  482.  
  483.  
  484. /************************ Advanced/Async routines ****************/
  485.  
  486. typedef pascal void (*NSpCallbackProcPtr)(
  487.     NSpGameReference             inGame, 
  488.     void*                         inContext, 
  489.     NSpEventCode                 inCode, 
  490.     OSStatus                     inStatus, 
  491.     void*                         inCookie);
  492.  
  493. OSStatus NSpInstallCallbackHandler(
  494.     NSpCallbackProcPtr             inHandler, 
  495.     void*                        inContext);
  496.  
  497.  
  498. typedef pascal Boolean (*NSpJoinRequestHandlerProcPtr)(
  499.     NSpGameReference             inGame, 
  500.     NSpJoinRequestMessage*        inMessage, 
  501.     void*                         inContext,
  502.     Str255                        outReason);
  503.  
  504. OSStatus NSpInstallJoinRequestHandler(
  505.     NSpJoinRequestHandlerProcPtr inHandler, 
  506.     void*                        inContext);
  507.  
  508.  
  509. typedef pascal Boolean (*NSpMessageHandlerProcPtr)(
  510.     NSpGameReference             inGame, 
  511.     NSpMessageHeader*            inMessage, 
  512.     void*                         inContext);
  513.  
  514. OSStatus NSpInstallAsyncMessageHandler(
  515.     NSpMessageHandlerProcPtr     inHandler, 
  516.     void*                        inContext);
  517.  
  518.  
  519.  
  520.  
  521. #ifdef __cplusplus
  522. }
  523. #endif
  524.  
  525. #ifdef __CFM68K__
  526. #pragma import reset
  527. #endif
  528.  
  529. /* NetSprocket Error Codes */
  530. enum
  531. {
  532.     kNSpInitializationFailedErr         = -30360,
  533.     kNSpAlreadyInitializedErr             = -30361,
  534.     kNSpTopologyNotSupportedErr         = -30362,
  535.     kNSpPipeFullErr                         = -30364,
  536.     kNSpHostFailedErr                     = -30365,
  537.     kNSpProtocolNotAvailableErr         = -30366,
  538.     kNSpInvalidGameRefErr                 = -30367,
  539.     kNSpInvalidParameterErr             = -30369,
  540.     kNSpOTNotPresentErr                 = -30370,
  541.     kNSpOTVersionTooOldErr                = -30371,
  542.     kNSpMemAllocationErr                 = -30373,
  543.     kNSpAlreadyAdvertisingErr             = -30374,
  544.     kNSpNotAdvertisingErr                 = -30376,
  545.     kNSpInvalidAddressErr                 = -30377,
  546.     kNSpFreeQExhaustedErr                = -30378,
  547.     kNSpRemovePlayerFailedErr            = -30379,
  548.     kNSpAddressInUseErr                    = -30380,
  549.     kNSpFeatureNotImplementedErr        = -30381,
  550.     kNSpNameRequiredErr                 = -30382,
  551.     kNSpInvalidPlayerIDErr                 = -30383,
  552.     kNSpInvalidGroupIDErr                 = -30384,
  553.     kNSpNoPlayersErr                     = -30385,
  554.     kNSpNoGroupsErr                     = -30386,
  555.     kNSpNoHostVolunteersErr             = -30387,
  556.     kNSpCreateGroupFailedErr             = -30388,
  557.     kNSpAddPlayerFailedErr                 = -30389,
  558.     kNSpInvalidDefinitionErr            = -30390,
  559.     kNSpInvalidProtocolRefErr            = -30391,
  560.     kNSpInvalidProtocolListErr            = -30392,
  561.     kNSpTimeoutErr                        = -30393,
  562.     kNSpGameTerminatedErr                = -30394,
  563.     kNSpConnectFailedErr                = -30395,
  564.     kNSpSendFailedErr                    = -30396,
  565.     kNSpMessageTooBigErr                = -30397,
  566.     kNSpCantBlockErr                    = -30398,
  567.     kNSpJoinFailedErr                    = -30399
  568. };
  569.  
  570.  
  571.  
  572. #if PRAGMA_IMPORT_SUPPORTED
  573. #pragma import off
  574. #endif
  575.  
  576. #if PRAGMA_ALIGN_SUPPORTED
  577. #pragma options align=reset
  578. #endif
  579.  
  580. #endif /* __NETSPROCKET__ */
  581.